API Specification

Specification	Description
OpenAPI (Swagger)	The most popular and widely adopted specification. Describes REST APIs in YAML or JSON.
RAML (RESTful API Modeling Language)	Designed for modeling REST APIs. Less popular now but still used.
API Blueprint	Markdown-based spec for writing and testing REST APIs.
JSON:API	Opinionated spec focused on data structures in REST APIs.
GraphQL SDL	Not REST-based, but defines GraphQL APIs declaratively.
WSDL	Used for SOAP APIs, not REST.

OpenAPI Specification

OpenAPI Specification is a language-agnostic standard for defining REST APIs. Originally developed by Swagger, it’s now maintained by the OpenAPI Initiative (under the Linux Foundation).

It’s typically written in YAML or JSON and can be used to:

• Auto-generate interactive documentation.
• Generate server/client code.
• Generate mock servers.
• Drive contract testing.

OpenAPI versions: 2.0 (Swagger), 3.0, and now 3.1.

OpenAPI Core Structure

openapi: 3.0.3
info:
  title: API title
  version: 1.0.0
  description: API description

servers:
  - url: https://api.example.com/v1

paths:
  /resource:
    get:
      summary: Get resource
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"

components:
  schemas:
    Resource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string